Inside Macintosh: QuickDraw GX Objects /

Chapter 5 - Ink Objects / About Ink Objects

Ink Properties

The interface to ink objects is entirely procedural. You manipulate the information in an ink object by modifying its properties using QuickDraw GX functions.

Ink objects have five accessible properties, as shown in Figure 5-1. Note that, because
an ink is an object and not a data structure, the order of the properties as shown in Figure 5-1 is completely arbitrary. Properties in italics are references to other objects.

Figure 5-1 The ink object and its properties

These are the five accessible properties in an ink object:

• Color. A data structure that specifies the color to use for drawing the shape associated with this ink object. Besides the numeric value of the color itself, the color structure includes a specification of the color space the color is defined in terms of, as well as optional references to two other QuickDraw GX objects, a color set and a color profile.
• Transfer mode. The way, or mode, of transferring the color to its destination (the screen or printed page or other location into which the shape associated with this ink is drawn). Transfer mode is a specification (such as "copy" or "XOR" or "blend") of the interaction between the color in this ink object and the existing color or colors of the destination. With transfer mode you can make a shape opaque or transparent, draw only part of it, change its color, or combine its color with the destination color in many different ways.

  The transfer mode also includes a specification of a color space and may include references to a color set and a color profile.

• Attributes. A set of flags that allow you to control certain properties of view ports that affect how colors appear when a shape is drawn.
• Owner count. The number of existing references to this ink object.
• Tag list. A list of references to custom information about this ink object, stored in private data structures called tag objects. The chapter "Tag Objects" in this book describes tag objects in general and how you can use them to add custom information to objects.

QuickDraw GX provides functions to manipulate each of these ink object properties.

Color

One main purpose of an ink object's existence is to specify the color of a shape. Because there is only one ink object per shape, it follows that each QuickDraw GX shape can have only one color. The only exception to this is for bitmap shapes, which use pixel values rather than an ink object to specify colors. (Picture shapes have no color at all apart from the colors of their component shapes, and thus do not use their ink object.)

The color in an ink object is defined with a gxColor structure:

struct gxColor{
   gxColorSpace         space;
   gxColorProfile       profile;
   union {
         struct gxCMYKColor      cmyk;
         struct gxRGBColor       rgb;
         struct gxRGBAColor      rgba;
         struct gxHSVColor       hsv;
         struct gxHLSColor       hls;
         struct gxXYZColor       xyz;
         struct gxYXYColor       yxy;
         struct gxLUVColor       luv;
         struct gxLABColor       lab;
         struct gxYIQColor       yiq;
         gxColorValue            gray;
         struct gxGrayAColor     graya;
         unsigned short          pixel16;
         unsigned long           pixel32;
         struct gxIndexedColor   indexed;
         gxColorValue            component[4];
   } element;
};

The color structure specifies three characteristics of a color:

• the color's color space, which tells what kind of format the color has--such as red-green-blue (RGB), hue-saturation-value (HSV), or luminance (grayscale).
• a reference to a color profile object that contains information for converting the device-independent color in this ink object into color-corrected values on a particular output device. If the reference is nil, the QuickDraw GX default color profile is used.
• the numeric color values that (for the given color space) specify the color of this ink object. An individual color has one number for each dimension, or color component, in the color's color space; for example, an RGB color value consists of three color component values. A color may consist of a maximum of four components.

To set and manipulate the color of an ink object requires an understanding of how color works in QuickDraw GX. The color structure, color spaces, and color profiles are all described in detail in the chapter "Colors and Color-Related Objects" in this book.

Transfer Mode

The transfer mode in an ink object is contained in a gxTransferMode structure:

struct gxTransferMode{
   gxColorSpace               space;      
   gxColorSet                 set;
   gxColorProfile             profile;
   Fixed                      sourceMatrix[5][4];
   Fixed                      deviceMatrix[5][4];
   Fixed                      resultMatrix[5][4];
   gxTransferFlag             flags;
   struct gxTransferComponent component[4];
};

Like the color structure just described, the transfer mode structure specifies a color space, and may contain a reference to a color profile object or a color set object, which contains an array of available colors. A transfer mode specifies its own color space because it can perform its operations according to its own definitions of color, independent of the color specifications in the rest of the ink object.

The transfer mode structure contains three 5 4 matrices (5 rows, 4 columns), the source matrix, device matrix, and result matrix, which it can use to transform colors for special effects, by blending proportions of the colors' components. In addition, it contains a set of transfer mode flags that control several aspects of the transfer mode operation.

The structure also contains up to four transfer components, used along with the matrices in the transfer mode operation. Transfer components contain the actual specification of the mode of transfer to use when drawing. Transfer components are defined by the gxTransferComponent structure:

struct gxTransferComponent{
      gxComponentMode   mode;
      gxComponentFlag   flags;
      gxColorValue      sourceMinimum;
      gxColorValue      sourceMaximum;
      gxColorValue      deviceMinimum;
      gxColorValue      deviceMaximum;
      gxColorValue      clampMinimum;
      gxColorValue      clampMaximum;
      gxColorValue      operand;
};

A transfer component contains a component mode specifying the type of transfer mode (like "copy" or "XOR") to use, an operand to apply (if the type calls for an operand), a set of maximum and minimum color values, and a set of flags. There is one transfer component for each color component (dimension) in the transfer mode's color space. Each of the transfer components in the transfer mode structure may specify a different component mode, which means that each dimension of a color space can be drawn with a different transfer mode when a shape is drawn.

How these parts of the transfer mode structure and transfer component structure define the transfer mode for drawing, and how you can use transfer modes to obtain the proper effect when drawing, are described in the section "About Transfer Modes" beginning on page 5-11.

Ink Attributes

Each ink object has a set of ink attributes, a group of flags that affect the dithering and halftoning behavior when the shape associated with the ink is drawn. Dithering is the use of repeating patterns of differently colored pixels to simulate colors not available in a view device's color space. Halftoning is the process of representing varying color intensity with evenly spaced dots of one color (but of different sizes) separated by a background of another color. The dither level and the halftone characteristics for all drawing to a view port are specified in the view port object, but you can use an ink object's attributes to affect them for individual shapes that use that ink.

Ink attributes allow you to turn halftoning or dithering on or off, and to affect both the number of colors used in dithering and the alignment of the patterns of dithered pixels. Table 5-1 lists the ink attribute constants and describes what each one means. The constants are defined in the gxInkAttributes enumeration.

Ink attributes (Continued)

Constant	Value	Explanation
gxPortAlignDitherInk	0x0001	If set, QuickDraw GX aligns the dither pattern to the view device coordinates. If this attribute is clear (the default), QuickDraw GX aligns the dither pattern to the view port coordinates.
gxForceDitherInk	0x0002	If set, QuickDraw GX forces the dithering operation to use exactly the number of colors specified by the view port's dither level. If this attribute is clear, QuickDraw GX may use fewer colors (in a simpler dither pattern) when constructing the dither pattern.
gxSuppressDitherInk	0x0004	If set, QuickDraw GX ignores the view port dither level, if any, and draws without dithering.
gxSuppressHalftoneInk	0x0008	If set, QuickDraw GX ignores the view port halftone, if any, and draws without creating a halftone.

IMPORTANT

Make sure that the gxPortAlignDitherInk attribute is cleared in ports associated with windows, so that if the window is dragged, updates using dithered drawing will match the existing parts of the drawing. (The attribute is clear by default.)

Dithering, dither level, and halftones are described in more detail in the chapter "View-Related Devices" in this book.